home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 301-325 / disk_322 / gwin / gwin.doc < prev    next >
Text File  |  1992-05-06  |  81KB  |  2,112 lines
  1.  
  2.      17 Feb 1990                      GWIN            by Howard C. Anderson
  3.  
  4.  
  5.                               GWIN GRAPHICS SYSTEM
  6.      
  7.                           Author:  Howard C. Anderson
  8.                                1895 E. Auburn Dr.
  9.                                 Tempe, Az 85283
  10.                                  (602) 897-7425
  11.      
  12.      GWIN V1.0 (c) Copyright 1989 Howard C. Anderson  All rights reserved.
  13.      Software may be distributed for non-profit only.  This software is NOT
  14.                                    shareware.
  15.      
  16.      
  17.      The  Amiga  is  a  great  computer  but  don't  you think the graphics
  18.      interface involves a lot of drudgery?    I  mean  it  takes  almost  a
  19.      hundred  lines  of  code to set up enough trash and trivia to draw one
  20.      straight line segment.  (Refer to "Inside the Amiga"  by  John  Thomas
  21.      Berry - the example in the "Using Intuition" chapter, "The Creation of 
  22.      a Window in a Custom Screen".) 
  23.      
  24.      If  you  encapsulate  the  low-level  routines,  you  can simplify the
  25.      interface and still provide access to most of the low-level  features.
  26.      In addition, you can eliminate the possibility of GURUs. The trade-off 
  27.      of  course  is  ease-of-use,  virtual  windowing,  automatic clipping,
  28.      greatly simplified mouse and keyboard interaction, freedom from GURUs, 
  29.      automatic menu generation,  speed  of  application  development,  etc.
  30.      versus speed  of  execution.    If  your application needs extra speed
  31.      though, you can still call the Amiga low-level routines while in GWIN. 
  32.      You at least save yourself a lot of setup time because you can get any 
  33.      of five types of Amiga screens and a  window  up  by  using  just  ONE
  34.      PROCEDURE CALL.  
  35.      
  36.      Who needs GWIN?    I  do.   I am a mathematician who's been a software
  37.      engineer for quite some time.  The first machine I worked on  was  the
  38.      Philco  2000.  It was one of the largest and most powerful machines in
  39.      existence at the time (It had 1/5 the memory of the Amiga 2000 here on 
  40.      my desk and was probably slightly faster than the Amiga  for  floating
  41.      point calculations.) Graphics on the Philco 2000 consisted exclusively 
  42.      of assembly  language  programs  to produce plots on printers.  At two
  43.      runs per day maximum for compiling - and debugging  provided  for  via
  44.      200 page  core  dumps  it was all drudgery and I loved it.  I loved it
  45.      less as time went  on  but  there  is  great  mystique,  glamour,  and
  46.      prestige  associated  with  writing  programs  that  no  one  else can
  47.      understand or debug.  Is it the desire  for  such  past  glories  that
  48.      accounts for  the  sorts  of interfaces we have these days???  Perhaps
  49.      there is not enough time to neatly package things???  Perhaps the only 
  50.      possible   flexible   software    interfaces    are    of    necessity
  51.      mind-warpers???   Maybe  everyone  but  me  has  time  to  muck around
  52.      endlessly wondering from whence the next  GURU  or  screen  shattering
  53.      misunderstanding will arise???  
  54.      
  55.      I  agree that you lose flexibility when you go up one level but you do
  56.      gain development efficiency.  The applications  I  have  in  mind  are
  57.      scientific  applications  such  as  interactive  graphing and mapping.
  58.      Several years ago, I used a system called the  Graphics  Compatibility
  59.      System (GCS)  that  was  developed by the government.  That system was
  60.      not particularly fast but it certainly made development of  scientific
  61.      graphics applications  MUCH easier and faster.  The source code of GCS
  62.      (in FORTRAN) is available through the National  Technical  Information
  63.  
  64.  
  65.                                       -1-
  66.  
  67.  
  68.      17 Feb 1990                      GWIN            by Howard C. Anderson
  69.  
  70.  
  71.      Center. It is a very large system.  Trying to compile it and run it on 
  72.      an  Amiga  would probably allow you to relive some of the past glories
  73.      mentioned above.  Instead,  I  designed  a  system  with  capabilities
  74.      similar  to  GCS but with additional Amiga-specific features and wrote
  75.      this simple graphics system in the  C  language.    The  result  is  a
  76.      graphics system  that  I  refer  to  as  GWIN  (Graphic WINdow).  GWIN
  77.      includes many of the virtual windowing features that were part of  the
  78.      GCS  philosophy  and  also  includes and simplifies use of many of the
  79.      strictly Amiga features such as  menus  and  requesters.    Underlying
  80.      architecture   of  GWIN  has  much  in  common  with  most  high-level
  81.      two-dimensional graphics  systems.    "Fundamentals   of   Interactive
  82.      Graphics  Computer  Graphics",  the  classic text by Foley and Van Dam
  83.      describes well the  sort  of  mathematical  transformations,  clipping
  84.      algorithms, etc.  that are part of the GWIN system.  
  85.      
  86.      Over  the  years  there  have been many higher level graphics systems:
  87.      PLOT10, GCS, GKS, CORE, etc.  Most of them presumably  have  been  too
  88.      massive to  adapt  for  use  on the Amiga system.  I am unaware of any
  89.      high-level graphics system that provides the range of features on  the
  90.      Amiga system that is provided by GWIN.  
  91.      
  92.      The  goal of GWIN is to allow a person to write interactive scientific
  93.      graphics applications programs in C without having to master  all  the
  94.      complexities of the Amiga graphics system.  
  95.      
  96.      Here  is  a  program  that  draws  one straight line segment in a high
  97.      resolution interlaced window using GWIN and then waits for the user to 
  98.      press the left mouse button before exiting: 
  99.      
  100.          main()
  101.          {
  102.          float x,y;
  103.             ustart("high2",0.,100.,0.,100.);
  104.             umove(20.,20.);
  105.             udraw(50.,50.);
  106.             ugrin(&x,&y);
  107.             uend();
  108.          }
  109.      
  110.      Ahhhh... Isn't that better???  
  111.      
  112.      Other examples are provided in the GWIN EXAMPLES directory.  
  113.      
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                       -2-
  132.  
  133.  
  134.      17 Feb 1990                      GWIN            by Howard C. Anderson
  135.  
  136.  
  137.                             GWIN THEORY OF OPERATION
  138.      
  139.      
  140.      
  141.      FLOATING POINT 
  142.      
  143.      GWIN is intrinsically floating point.  Most of the  parameters  passed
  144.      to and from GWIN routines MUST BE FLOATING POINT. There are exceptions 
  145.      however  so  I  have  provided  the  type  of  each parameter with the
  146.      description of the calling sequence of each routine.  
  147.      
  148.      
  149.      
  150.      COORDINATE SYSTEM 
  151.      
  152.      Normal mathematical xy coordinate system  is  assumed  with  larger  x
  153.      values  to  the  right of the screen and larger y values at the top of
  154.      the screen.  (The machine manufacturers tend to put the small y values 
  155.      at the top of the  screen  because  that  is  where  the  raster  scan
  156.      starts.    This   is   an  unfortunate  accident  of  the  history  of
  157.      television.  If they had started the  raster  at  the  bottom  of  the
  158.      screen  and  gone  up  instead  of  vice-versa it would have been much
  159.      nicer.  (Surely you don't REALLY want to work in quadrant  IV  -  with
  160.      NEGATED  Y  values???) GWIN corrects for this historical, perpetuated,
  161.      accident.  
  162.      
  163.      
  164.      
  165.      STARTUP 
  166.      
  167.      Graphics operations are begun with a USTART procedure  call.    USTART
  168.      will  allow  you  to open any size window you choose on a screen whose
  169.      type you may choose.  Screen types are: 
  170.      
  171.      low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  172.      low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  173.      high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  174.      high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  175.      ham   - 320x200 pixel, hold and modify, [4096 colors].
  176.      
  177.      low1.backdrop - Same as low1 but active region fills screen.
  178.      low2.backdrop - Same as low2 but active region fills screen.
  179.      high1.backdrop - Same as high1 but active region fills screen.
  180.      high2.backdrop - Same as high2 but active region fills screen.
  181.      ham.backdrop - Same as ham but active region fills screen.
  182.      
  183.      
  184.      
  185.      ACTIVE REGION 
  186.      
  187.      When you open a screen and window with USTART, the  active  region  of
  188.      the Amiga  window is everything inside the borders.  This full area is
  189.      always thought of as running from 0.0 to 100.0 in both  the  x  and  y
  190.      directions.  
  191.      
  192.      You  may  use  UDAREA to select some subset of this area as the active
  193.      region.  UDAREA calls are always relative to the original 0.0 to 100.0 
  194.      bounds.  Drawing is always restricted to the active region by internal 
  195.  
  196.  
  197.                                       -3-
  198.  
  199.  
  200.      17 Feb 1990                      GWIN            by Howard C. Anderson
  201.  
  202.  
  203.      clipping routines unless you have turned internal clipping  off  using
  204.      uset("ncli").   (See  "Fundamentals of Interactive Computer Graphics",
  205.      Foley and  Van  Dam,  section  on  "Viewports"  if  you  need  further
  206.      information.) 
  207.      
  208.      
  209.      
  210.      VIRTUAL WINDOWING 
  211.      
  212.      Virtual windowing  is  automatic.    The  UWINDO command allows you to
  213.      change the size of the virtual window.  The default virtual window  is
  214.      from  0.0  to  100.0  in  the  x  direction  and 0.0 to 100.0 in the y
  215.      direction.  
  216.      
  217.      Whatever is in  the  virtual  window  is  expanded  or  contracted  as
  218.      necessary  and  mapped  onto the active region determined with UDAREA.
  219.      By changing UWINDO and redrawing, you can pan and zoom.  (Clearly,  we
  220.      are  not  talking  real-time  pan  and  zoom  here  of  course.)  (See
  221.      "Fundamentals of Interactive Computer Graphics", Foley  and  Van  Dam,
  222.      section on "Windows and Clipping" if you need further information.) 
  223.      
  224.      
  225.      
  226.      ROTATION OF COORDINATES 
  227.      
  228.      The coordinate system may be rotated through an angle theta (value 0.0 
  229.      through  360.0)  relative to any point in the virtual coordinate space
  230.      through use of the UROTATE call.  The point about which the coordinate 
  231.      space is rotated is ALWAYS with  respect  to  the  ORIGINAL  UNROTATED
  232.      COORDINATE  SYSTEM.  This  point becomes the new origin, (0,0), of the
  233.      new rotated coordinate system.  There is no  way  provided  to  rotate
  234.      Amiga text.    The  position  at  which  the text is to appear will be
  235.      rotated and the text will begin at the new position but it will  still
  236.      be horizontal like this line you are now reading.  
  237.      
  238.      
  239.      
  240.      DRAWING 
  241.      
  242.      UMOVE,  UDRAW,  UCRCLE,  URECT,  and  UPLYGN  are the primary line and
  243.      polygon drawing tools.  UMOVE moves the beam to the specified  virtual
  244.      point.   UDRAW  draws a line from the current virtual beam position to
  245.      the virtual beam position given  in  the  UDRAW  call.    Clipping  is
  246.      performed as  necessary.    URECT draws a rectangle and has some speed
  247.      advantages over UPLYGN.  UPLYGN  draws  a  polygon  of  the  specified
  248.      number  of  sides within a circumscribing circle of radius provided in
  249.      the call.  The optional "fill"  switch  set  via  a  USET  call  cause
  250.      polygons  or  rectangles  to  be  filled  when drawn and causes UMOVE,
  251.      UDRAW, UDRAW, UDRAW,... UMOVE sequences to be filled.  Setting  "nofi"
  252.      with  a USET call turns off the filling operation and closes and fills
  253.      immediately any UDRAW sequence that has not yet been closed by a UMOVE 
  254.      call.  
  255.      
  256.      
  257.      
  258.      TEXT 
  259.      
  260.      UFONT establishes the font that will be used for subsequent UPRINT and 
  261.  
  262.  
  263.                                       -4-
  264.  
  265.  
  266.      17 Feb 1990                      GWIN            by Howard C. Anderson
  267.  
  268.  
  269.      UPRNT1 calls.  Any font that you have on your system may be used.  The 
  270.      default is the standard Amiga default font  which  at  the  moment  is
  271.      Topaz. Its default size is selected by you with the Preferences tool.  
  272.      
  273.      UPRINT  will  print a line of text at the given location in accordance
  274.      with the USET options "inte", "real", and "text". UPRNT1 prints a line 
  275.      of text at the current beam location and allows  you  to  set  "inte",
  276.      "real", and "text" for the duration of the call.  
  277.      
  278.      
  279.      
  280.      COLOR 
  281.      
  282.      The current drawing color is established by a UPSET("colo",color) call 
  283.      where  color  is a real number between 0 and the maximum color for the
  284.      particular screen type you are using.  (GWIN does a modulus  operation
  285.      if  you  forget  and  exceed  the maximum color.) The "colo" option to
  286.      UPSET sets the A pen and the O pen so that lines, fills, and  outlines
  287.      are all  set to the designated color.  The "bcol" option to UPSET sets
  288.      the B pen so that  the  background  color  for  text  may  be  set  as
  289.      desired.  The "ccol" option to UPSET sets the color that will fill the 
  290.      screen when the UERASE screen clearing call is issued.  
  291.      
  292.      
  293.      
  294.      CLIPPING 
  295.      
  296.      Line and   polygon  clipping  are  automatic.    These  are  sometimes
  297.      suppressed if the item being drawn such as a polygon or  rectangle  is
  298.      seen to  fall  completely  inside  the  virtual  boundaries.   You may
  299.      suppress clipping for speed IF YOU ARE ABSOLUTELY CERTAIN THAT NONE OF 
  300.      THE THINGS YOU DRAW WILL FALL OUTSIDE OF THE CURRENT  VIRTUAL  WINDOW.
  301.      If  you  blow  it,  ANYTHING can happen - loss of screen synch, GURUs,
  302.      etc.  Clipping is disabled by the "ncli" option of USET.  Clipping  is
  303.      reenabled by the "clip" option of USET.  
  304.      
  305.      
  306.      
  307.      RECTANGLE INTERIOR ONLY FILL 
  308.      
  309.      If  you have a rectangle whose color you wish to change but you do not
  310.      wish to change the color of the bounding box,  use  USET("rint").  Use
  311.      USET("rext") to include the exterior bounding box if you wish.  
  312.      
  313.      
  314.      
  315.      GRAPHICS INPUT 
  316.      
  317.      UGRIN, UGRINC, UGRINL, UGRINA, and UIGRINA are provided.  
  318.      
  319.      Each  of these responds to the window close gadget by calling UEND and
  320.      exiting IMMEDIATELY. (Unless the USET option "nclo" is set for  UGRINC
  321.      and UGRINL in which case the CLOSEWINDOW event is returned to you.) 
  322.      
  323.      UGRIN  (GRaphic INput) returns the x and y location of the cursor when
  324.      the left mouse button is pressed.  
  325.      
  326.      UGRINC (GRaphic INput Character) returns the x and y location  of  the
  327.  
  328.  
  329.                                       -5-
  330.  
  331.  
  332.      17 Feb 1990                      GWIN            by Howard C. Anderson
  333.  
  334.  
  335.      cursor, the event type, and the keyboard character that was pressed if 
  336.      the   event   type  was  "VANILLAKEY".  Event  types  may  be  one  of
  337.      MOUSEBUTTONS,  VANILLAKEY,  CLOSEWINDOW  (only  if  you  have   called
  338.      uset("nclo")), or    REFRESHWINDOW.      If   the   event   type   was
  339.      "MOUSEBUTTONS", the key returned is an "a" if it was a left mouse  key
  340.      "down"  event  code  and  an "A" if it was a left mouse key "up" event
  341.      code.  MOUSEMOVE events are NOT monitored by UGRINC.  
  342.      
  343.      UGRINL (GRaphic INput Locator) returns the x and  y  location  of  the
  344.      cursor, the event type, and the keyboard character that was pressed if 
  345.      the event type was "VANILLAKEY". If the event type was "MOUSEBUTTONS", 
  346.      the key returned is an "a" if it was a mouse key "down" event code and 
  347.      an "A"  if  it  was a mouse key "up" event code.  MOUSEMOVE events ARE
  348.      monitored by UGRINL and you are notified immediately of the  last  one
  349.      in the current message stack.  
  350.      
  351.      UGRINA  (GRaphic INput All) is identical with UGRINL except it returns
  352.      even if no event occurred.  This allows you  to  continuously  monitor
  353.      user activity  while  in a processing loop.  You can use this to allow
  354.      the user to interrupt a process if  he  desires  (maybe  he  wants  to
  355.      change his mind regarding the 30 hour Mandelbrot drawing...) 
  356.      
  357.      UIGRINA  (Integer  GRaphic  INput All) is identical with UGRINA except
  358.      that  it  returns  integer  mouse  coordinates  with   no   coordinate
  359.      transformations performed.    This  allows  greatest  speed  since  it
  360.      bypasses all floating point  operations.    If  you  need  speed,  use
  361.      UIGRINA.  Coordinates  returned  are normal Amiga coordinates with the
  362.      origin at the top left corner of the screen.  (For  a  high-resolution
  363.      screen,  640x400 pixels, the x coordinate will be an integer from 0 to
  364.      639 and the y coordinate will be an integer from 0 to 399.) 
  365.      
  366.      
  367.      EASY AMIGA MENUS 
  368.      
  369.      With a one line call (UAMENU), you can set up  each  menu  item  of  a
  370.      hierarchical menu  structure.   GWIN creates all necessary structures,
  371.      allocates all necessary space.  You pass  a  "function  pointer"  that
  372.      tells  which  of  your  functions will be called when the user selects
  373.      that menu item.  
  374.      
  375.      
  376.      
  377.      EASY AMIGA YES/NO REQUESTER 
  378.      
  379.      With a one line  call  (UYORN),  you  can  put  up  an  AMIGA  boolean
  380.      requester containing  your  text.  When the user makes his choice, you
  381.      will receive a TRUE/FALSE return code.  
  382.      
  383.      
  384.      
  385.      EASY AMIGA STRING REQUESTER 
  386.      
  387.      With a one line call (UGETSTRING), you can  put  up  an  amiga  string
  388.      requester containing  your  prompt  text.  The requester will wait for
  389.      the user to enter a text string.  The requester exits when a  carriage
  390.      return is received.  
  391.      
  392.      
  393.  
  394.  
  395.                                       -6-
  396.  
  397.  
  398.      17 Feb 1990                      GWIN            by Howard C. Anderson
  399.  
  400.  
  401.      
  402.      SCREEN DUMP TO PRINTER 
  403.      
  404.      If  you have an Epson LQ series printer, you can dump the screen image
  405.      to the printer using UPRSCR.  
  406.      
  407.      
  408.      
  409.      ABORT 
  410.      
  411.      GWIN has its own  abort  handler  so  that  GWIN  can  be  aborted  if
  412.      desired.    The   abort  is  graceful,  i.e.,  all  memory  areas  are
  413.      deallocated, all libraries released,  etc.    If  you  have  your  own
  414.      cleanup  handler  (via USETCLEANUP) it will receive control after GWIN
  415.      completes its cleanup after an abort condition occurs.  
  416.      
  417.      Note: The above is true for MANX compiler.  I've accomplished this  by
  418.      overlaying  the  _abort() function described on page lib68.ap.1 of the
  419.      version 3.6 Manx compiler manual.   Within  the  Lattice  environment,
  420.      Glen  Fullmer  (my  good friend and associate who compiled the LATTICE
  421.      versions using his LATTICE  compiler)  used  the  SIGNAL  function  to
  422.      attempt to catch the "SIGINT" signal.  Neither of us is impressed with 
  423.      either compiler's  abilities  in this area.  On page lib68.ap23 of the
  424.      MANX compiler manual, we are told that  the  only  signals  "currently
  425.      supported" are  "SIGFPE",  "SIGILL",  and  "SIGSEGV".  The example two
  426.      pages later (page lib68.ap.25) illustrates use of the SIGNAL  function
  427.      USING "SIGINT"!!  How quickly they forget...  
  428.      
  429.      (While      I'm      on     the     subject     of     well-documented
  430.      things-that-are-not-there, you should try looking  for  the  "realloc"
  431.      function  described  under "malloc" on page lib.31 of the MANX manual.
  432.      I really could have used "realloc" last week...) 
  433.      
  434.      
  435.      
  436.      USER CLEANUP HANDLER 
  437.      
  438.      The routine USETCLEANUP allows you to pass a function pointer to  GWIN
  439.      that points  to  your  own  cleanup  routine.    When  GWIN exits, for
  440.      whatever reason, if you specified a cleanup routine, control  will  be
  441.      passed  to  your  cleanup routine after GWIN completes deallocation of
  442.      its memory allocations, release  of  its  libraries,  etc.    In  your
  443.      cleanup  routine,  you  may  then  release  any  storage  you may have
  444.      allocated, close any files, etc.  
  445.      
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                       -7-
  462.  
  463.  
  464.      17 Feb 1990                      GWIN            by Howard C. Anderson
  465.  
  466.  
  467.                                     EXAMPLES
  468.      
  469.      Examples of the use of GWIN routines are located in the  gwin/examples
  470.      directory.   Execute these examples and study their source code to see
  471.      how to use GWIN calls.  
  472.      
  473.      The examples and a brief description of each are as follows: 
  474.      
  475.           clipdemo 
  476.           
  477.                Demonstrates setup of a GWIN clipping window within an Amiga 
  478.                window.  
  479.                
  480.           
  481.           colormap2 
  482.           
  483.                Demonstrates changing the colormap.  Place cursor  inside  a
  484.                triangle,  depress left mouse button and move cursor around.
  485.                The points of the triangles correspond  to  Red,  Green  and
  486.                Blue.  Distance  from  the  center  determines how much Red,
  487.                Green or Blue.  
  488.                
  489.           
  490.           placeobject 
  491.           
  492.                Demonstrates moving  and  placing  a  rectangle  of  various
  493.                colors.  
  494.                
  495.           
  496.           
  497.           rubberbandline 
  498.           
  499.                Demonstrates a  rubberband  line.  Simple demo intended only
  500.                to illustrate how a rubberband line is generated.    (Object
  501.                code was deleted to make this all fit on one disk.  You must 
  502.                recompile before running this program.) 
  503.                
  504.           
  505.           
  506.           text 
  507.           
  508.                Demonstrates  use of font selection and various text display
  509.                options.  (Object code was deleted to make this all  fit  on
  510.                one disk.  You must recompile before running this program.) 
  511.                
  512.           
  513.           
  514.           graph 
  515.           
  516.                Accepts  a  list of numbers either from the keyboard or from
  517.                standard input.    The  numbers  are   assumed   to   be   Y
  518.                coordinates.    Integer   X  coordinates  are  automatically
  519.                assigned.  A graph is drawn.  Menu options  allow  switching
  520.                between line graph and bar graph modes.  If you place a list 
  521.                of  numbers  in  a  file  (say file1) then issue the command
  522.                "graph <file1", the numbers will be graphed.  
  523.                
  524.           
  525.  
  526.  
  527.                                       -8-
  528.  
  529.  
  530.      17 Feb 1990                      GWIN            by Howard C. Anderson
  531.  
  532.  
  533.           
  534.           request 
  535.           
  536.                Shows how to use a  requester  to  ask  the  user  a  yes/no
  537.                question.  
  538.                
  539.           
  540.           
  541.           screentypes 
  542.           
  543.                Demonstrates all 10 types of screens supported by GWIN.  
  544.                
  545.           
  546.           
  547.           three-d 
  548.           
  549.                Allows construction of three-dimensional figures.  You would 
  550.                need  red/blue  glasses  to see the three-dimensional effect
  551.                however.  (Object code was deleted to make this all  fit  on
  552.                one disk.  You must recompile before running this program.) 
  553.                
  554.           
  555.           
  556.           menu 
  557.           
  558.                Demonstrates how to build and use menus in GWIN.  
  559.                
  560.           
  561.           
  562.           rubberbandbox 
  563.           
  564.                Demonstrates building boxes using a rubberband box.  
  565.                
  566.           
  567.           
  568.           spiceplot 
  569.           
  570.                For you Electrical Engineers who have access to some version 
  571.                of the "SPICE" program.  Spiceplot reads a SPICE output file 
  572.                from standard input, i.e., type: "spiceplot <spiceoutput" to 
  573.                see it  plot curves contained in the spiceoutput file.  Note
  574.                the format of the data in the spiceoutput file.    Spiceplot
  575.                is looking  for  the  lists  of node data.  Depress the left
  576.                mouse button and hold, drag, and release.  A rubberband  box
  577.                will  have appeared and the selected region will be expanded
  578.                to fill the screen.  Use the menu to restore the  curves  to
  579.                their original  scale.  As the cursor moves, the coordinates
  580.                are displayed.  
  581.                
  582.           
  583.           
  584.           geomap 
  585.           
  586.                A geographic mapping system.  I'm only plotting  grid  lines
  587.                so don't  expect  to see a world map.  I used to have access
  588.                to the almost 6,000,000 latitude/longitude points  in  World
  589.                Data Bank II.   I do not have it at the moment.  If YOU have
  590.                it and could send it or portions of it to me I would GREATLY 
  591.  
  592.  
  593.                                       -9-
  594.  
  595.  
  596.      17 Feb 1990                      GWIN            by Howard C. Anderson
  597.  
  598.  
  599.                appreciate it.  Call me at home at  (602)  897-7425.  Geomap
  600.                asks  for  latitude  and  longitude coordinates of where you
  601.                wish the center of the map  to  be.    I  used  some  simple
  602.                coordinate transformations that allow a lot of power without 
  603.                a lot  of  work.    Note  that the cursor reads latitude and
  604.                longitude as it is moved.   Note  menu  options.    We  have
  605.                orthographic  and  Mercator  projections  available with the
  606.                transverse Mercator projection thrown in  for  free.    Note
  607.                that   the   cursor  also  provides  accurate  latitude  and
  608.                longitude data when a transverse projection is displayed.  
  609.                
  610.                The "ortho2" menu option simply draws the back side  of  the
  611.                globe in blue and the front side in red.  "Ortho" only draws 
  612.                the front side.  
  613.                
  614.           
  615.           
  616.           speedy 
  617.           
  618.                Demonstrates how Amiga calls can be used within a screen and 
  619.                window  initiated  by  GWIN. GWIN saved all of the effort of
  620.                bringing up a special screen and window while allowing  full
  621.                use of  all standard Amiga graphics functions.  Speedy makes
  622.                use of direct Amiga graphics function calls to  provide  the
  623.                fastest possible  graphics  operations.  This means that for
  624.                special purposes, it is  possible  to  bypass  the  floating
  625.                point  world/screen  coordinate  transformations  that are a
  626.                part of normal GWIN operation.    The  function  uigrina  is
  627.                provided  to  allow  transformationless  return  of  x and y
  628.                cursor coordinates for greatest possible speed.  The slowest 
  629.                thing in "speedy" is perhaps the call to the  random  number
  630.                generator, "ran".  
  631.                
  632.      
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.                                       -10-
  660.  
  661.  
  662.      17 Feb 1990                      GWIN            by Howard C. Anderson
  663.  
  664.  
  665.                                    USING GWIN
  666.      
  667.      I am using the MANX C compiler.  When I began this project I foolishly 
  668.      assumed that compilers on the Amiga produced compatible object modules 
  669.      as  is  done  on  Sun, Apollo, Multics, IBM, etc., computer systems so
  670.      that they could be linked together with  object  modules  produced  by
  671.      other compilers.    Alas,  Amiga  does  not  have a standard linker so
  672.      Lattice and Manx each apparently wrote their own and defined their own 
  673.      standards so Lattice C object modules cannot be  linked  with  MANX  C
  674.      object modules.  
  675.      
  676.      I  then thought that maybe I could organize GWIN as an "Amiga library"
  677.      and overcome this defect but after researching the "ELIB" code on Fish 
  678.      disk 87 and the Mklib code on Fish disk 183  I  concluded  that  Amiga
  679.      libraries would result in another open-ended research program into why 
  680.      another  aspect of the Amiga system requires hundreds of lines of code
  681.      when what I expect is a  one-liner.    I  see  how  to  do  it  (after
  682.      receiving  a  few  suggestions  from people on USENET) but it requires
  683.      massive restructuring.   The  assembly  language  generated  by  Mklib
  684.      assumes integer   parameters  rather  than  floating  point.    I  did
  685.      successfully generate (via mklib and  alterations  by  hand)  a  small
  686.      library that  accepted floating point and fixed point arguments.  This
  687.      was a very time-consuming exercise.  This also required research  into
  688.      RemLib  (Fish  139  and  Fish  178)  to figure out how to make a newly
  689.      compiled library take effect.    Reinstalling  the  library  does  not
  690.      necessarily cause  the previous version to go away.  THINKING that you
  691.      have updated a piece of code when in actuality the old version remains 
  692.      in effect indefinitely can be truly frustrating.  
  693.      
  694.      Library reentrancy was automatically handled by  the  Multics  system.
  695.      On the  Amiga,  reentrancy  is do-it-yourself.  I see how to do it all
  696.      and make it all work but the effort required is truly prodigious.   (I
  697.      reject  the  philosophy  that requires passing a pointer to the user's
  698.      own storage area in EVERY call, such as  is  done  with  the  RastPort
  699.      pointer.  Operating  systems should handle these things.  I admit that
  700.      my stubborness on this issue complicates things for me.  P.S. ... Some 
  701.      time has passed since I wrote the last three sentences.    I'm  slowly
  702.      coming around but I still think passing the pointer is yucky.) 
  703.      
  704.      Areas such as transmitting error messages from within an Amiga library 
  705.      to the  user  are  still  unclear.    For example if someone blows the
  706.      USTART or UDAREA parameters, how does one notify  the  developer  from
  707.      within the  library?    (If  you said GURU, you still don't understand
  708.      what I've been trying to  say  about  making  things  easier  for  the
  709.      developer...   Please  read  the previous paragraphs again.) You can't
  710.      use PRINTF. It GURUs. Would a requester work??    I  haven't  tried  a
  711.      requester  but  then  I  don't  have  unlimited  time  to  try all the
  712.      alternatives searching for something  that  might  accidentally  work.
  713.      Whatever it is should ALWAYS work also.  I don't have time to test all 
  714.      THOSE possibilities either.  
  715.      
  716.      
  717.      
  718.      LATTICE NOTES 
  719.      
  720.      I have a  MANX  compiler.    I  don't  have  a Lattice compiler.  Glen
  721.      Fullmer, my good friend and associate, does have  a  Lattice  compiler
  722.      and  graciously  offered  to  create  Lattice-compatible  GWIN  object
  723.  
  724.  
  725.                                       -11-
  726.  
  727.  
  728.      17 Feb 1990                      GWIN            by Howard C. Anderson
  729.  
  730.  
  731.      modules.  I am not a Lattice guru so what we'll  do  for  you  Lattice
  732.      users  is list the names of the Lattice-compatible GWIN object modules
  733.      here, show a tiny  bit  of  makefile  data  here  and  tell  you  that
  734.      everything  works in a manner similar to the way the Manx versions are
  735.      used.  The Lattice-compatible GWIN object modules are: 
  736.      
  737.              gwinl.ff.o
  738.              gwinl.fiCD.o
  739.      
  740.      The ff, ffCD, and fiCD labels have the same meaning as given below  in
  741.      the  descriptions  of  the  corresponding  MANX-compatible versions of
  742.      GWIN.  
  743.      
  744.      Glen  says  he  believes  gwinl.fiCD.o  can  be  used  in   place   of
  745.      gwinl.ffCD.o.  
  746.      
  747.      The  makefile  entry used to compile the GWIN object module gwinl.ff.o
  748.      looked like this: 
  749.      
  750.       gwinl.ff.o: gwin.v1.c gwin.h 
  751.           lc -ff -cw -ogwinl.ff.o gwin.v1.c 
  752.      
  753.      
  754.      The makefile used to link gwinl.ff.o with  the  example  placeobject.c
  755.      looked like this: 
  756.      
  757.       CFLAGS = -ff -O 
  758.       LIBTYPE = ffp 
  759.       COMPILETYPE = f 
  760.      
  761.       placeobject: placeobject.o gwinl.f$(COMPILETYPE).o 
  762.            blink lib:c.o placeobject.o 
  763.                   gwinl.f$(COMPILETYPE).o 
  764.                   lib lib:lcm$(LIBTYPE).lib 
  765.                   lib:lc.lib lib:amiga.lib 
  766.      
  767.       placeobject.o: placeobject.c 
  768.            lc $(CFLAGS) placeobject.c 
  769.      
  770.      
  771.      NOTE: The  "blink" line above has been folded to fit on this page.  it
  772.      and the next three lines should all be on one line.  
  773.      
  774.      Now just one more thing...   I  have  not  been  having  a  good  time
  775.      figuring  out  what  sort  of  "wierding  way"  was  used by the Amiga
  776.      designers to handle font loading.  Nothing seems to be exactly  right.
  777.      Rather  than  put  Glen through another painful compilation process, I
  778.      have made a small change to the MANX version  that  is  not  currently
  779.      reflected in  the  Lattice version.  The MANX version always reads the
  780.      font from the disk.  This is slower but always gets exactly  what  you
  781.      ask for  with respect to size and style.  The Lattice version tries to
  782.      read the font from the system first then from the disk if  the  system
  783.      read failed.    The  read  from  the  system often is satisfied if the
  784.      resultant font is "close" to what you want.    Reading  from  disk  is
  785.      slower  and  each  time  a  font  is read from disk, memory appears to
  786.      disappear.  This memory does not reappear  after  termination  of  the
  787.      program.   A note from someone on USENET indicated that this memory is
  788.      not really "gone" however and will be recovered as soon as some memory 
  789.  
  790.  
  791.                                       -12-
  792.  
  793.  
  794.      17 Feb 1990                      GWIN            by Howard C. Anderson
  795.  
  796.  
  797.      allocation request asks for more than appears to  be  left.    I  have
  798.      tried this and  they  are  right.    Its  REALLY  goofy.    I've tried
  799.      "AvailFonts" - It doesn't seem to update the "system font list".  I've 
  800.      tried a lot of things but a lot of "smart" interaction is  built  into
  801.      the Amiga  font  loading  processes  apparently.  Perhaps a little too
  802.      smart.  Hopefully I will figure this out  eventually  and  provide  an
  803.      updated version some time in the future.  
  804.      
  805.      Thats it regarding Lattice. Now back to MANX.  
  806.      
  807.      
  808.      
  809.      MANX NOTES 
  810.      
  811.      To  use  the  GWIN  library,  you  must  write  a C program that calls
  812.      procedures in the GWIN library, compile it with the Manx compiler  and
  813.      link the  object module with the GWIN object module.  (The makefile in
  814.      the gwin/examples directory  shows  many  examples  of  compiling  and
  815.      linking with GWIN.) 
  816.      
  817.      Fortunately  or  unfortunately  depending  on  the degree to which you
  818.      appreciate simplification, there  are  three  floating  point  formats
  819.      allowed  by  the  Manx  compiler,  the  "Motorola Fast Floating Point"
  820.      format, the "IEEE Double Precision Floating Point  Emulation"  format,
  821.      and the  "68881 Floating Point" format.  In addition, there are "large
  822.      code / small code" and "large data / small data" compiler options.  We 
  823.      could have compiled 12 versions but we didn't.  We chose to make three 
  824.      versions of the object code, a fast floating point, small code / small 
  825.      data version, a fast floating point large code /  large  data  version
  826.      and an IEEE large code / large data version.  The compiler options for 
  827.      these  are,  respectively,  "+ff",  "+ff  +C  +D",  and "+fi +C +D". A
  828.      version of GWIN has therefore been compiled for each of these  formats
  829.      so  you may link the one that is compatible with your mainline program
  830.      and the capabilities of your machine.  The three versions of GWIN  are
  831.      "gwin.ff.o", "gwin.ffCD.o", and "gwin.fiCD.o".  
  832.      
  833.      For  the greatest speed, you should use "gwin.ff.o" unless the size of
  834.      your data or code requires use of the  slower  "gwin.ffCD.o"  version.
  835.      Version  "gwin.fiCD.o"  should  be  used  if  you  need high precision
  836.      arithmetic.  Remember that YOUR object segments must be compiled so as 
  837.      to be compatible with the version you select.  
  838.      
  839.      There is also a potential problem with the default size  of  integers.
  840.      The  three  versions of GWIN were compiled with the MANX C compiler +L
  841.      option so it assumes long integers.  That means that the GWIN routines 
  842.      expect to link up with the  "lm32"  and  "lc32"  libraries.    If  you
  843.      instead link with "lm" and/or "lc" problems will probably occur.  
  844.      
  845.      If  you  don't  want to experiment, compile your programs using the +L
  846.      option!  
  847.      
  848.      So that you will not be in the dark, the  GWIN  object  segments  were
  849.      compiled with these statements: 
  850.      
  851.              cc +ff +L -o gwin.ff.o gwin.c
  852.              cc +ff +L +C +D -o gwin.ffCD.o gwin.c
  853.              cc +fi +L +C +D -o gwin.fiCD.o gwin.c
  854.      
  855.  
  856.  
  857.                                       -13-
  858.  
  859.  
  860.      17 Feb 1990                      GWIN            by Howard C. Anderson
  861.  
  862.  
  863.      
  864.      Assume you have a program named "prog.c" that calls GWIN routines such 
  865.      as "ustart",  "umove",  etc.    Then to compile and link it, you would
  866.      execute the statements: 
  867.      
  868.           cc +ff +L prog.c 
  869.      
  870.      This will result in an object segment called "prog.o".  To  link  GWIN
  871.      in with your object segment, issue the link command: 
  872.      
  873.           ln prog.o gwin.ff.o -lm32 -lc32 
  874.      
  875.      This will result in the executable graphics module "prog".  
  876.      
  877.      
  878.      
  879.      Similarly,  to use the fast floating point format large code and large
  880.      data version, you would compile your program with: 
  881.      
  882.           cc +fi +C +D +L prog.c 
  883.      
  884.      You would link this with GWIN by using the command: 
  885.      
  886.           ln prog.o gwin.ffCD.o -lml32 -lcl32 
  887.      
  888.      
  889.      
  890.      Similarly, to use the IEEE format, large code /  large  data  version,
  891.      you would compile your program with: 
  892.      
  893.           cc +fi +C +D +L prog.c 
  894.      
  895.      You would link this with GWIN by using the command: 
  896.      
  897.           ln prog.o gwin.fi.o -lmal32 -lcl32 
  898.      
  899.      
  900.      
  901.      
  902.      (Hint  -  always use the IEEE version for debugging then recompile and
  903.      link using +ff and lm32 for speed.  SDB ALWAYS seems to interpret your 
  904.      numbers as IEEE formatted numbers.  The  12  options  were  apparently
  905.      confusing for the MANX people too?) 
  906.      
  907.      
  908.      Now  if  you wish to simplify further for day-to-day use, you can make
  909.      one of the GWIN object modules a "library" module (this is  the  OTHER
  910.      type  of  "library", like the ones in "sys:lib".) For the "ff" version
  911.      of GWIN this would be done by issuing the statement: 
  912.      
  913.           lb sys:lib/gwin.lib gwin.ff.o 
  914.      
  915.      Linking your program, prog.o, would then be done with the statement: 
  916.      
  917.           ln prog.o -lgwin -lm32 -lc32 
  918.      
  919.      The advantage is that you don't have to remember  where  you  put  the
  920.      GWIN object module.  
  921.  
  922.  
  923.                                       -14-
  924.  
  925.  
  926.      17 Feb 1990                      GWIN            by Howard C. Anderson
  927.  
  928.  
  929.      
  930.      
  931.      
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.  
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.                                       -15-
  990.  
  991.  
  992.      17 Feb 1990                      GWIN            by Howard C. Anderson
  993.  
  994.  
  995.                                 PROCEDURE CALLS
  996.      
  997.      ustart(mode,xmin,xmax,ymin,ymax);
  998.      char mode[255];
  999.      float x1,x2,y1,y2;
  1000.      
  1001.           Starts everything.    Creates  a  screen  and a window within the
  1002.           screen within which all graphics operations will occur.  
  1003.           
  1004.           Mode is "low1", "low2", "high1", "high2",  or  "ham"  or  any  of
  1005.           these with a ".backdrop" appended.  
  1006.           
  1007.           low1  - 320x200 pixel, low resolution, non-interlaced, 32 colors.
  1008.           low2  - 320x400 pixel, low resolution, interlaced, 16 colors.
  1009.           high1 - 640x200 pixel, high resolution, non-interlaced, 32 colors.
  1010.           high2 - 640x400 pixel, high resolution, interlaced, 16 colors.
  1011.           ham   - 320x200 pixel, hold and modify, [4096 colors].
  1012.           
  1013.           low1.backdrop - Same as low1 but active region fills screen.
  1014.           low2.backdrop - Same as low2 but active region fills screen.
  1015.           high1.backdrop - Same as high1 but active region fills screen.
  1016.           high2.backdrop - Same as high2 but active region fills screen.
  1017.           ham.backdrop - Same as ham but active region fills screen.
  1018.           
  1019.           
  1020.           xmin determines the window x-pixel minimum value on the screen.
  1021.           xmax determines the window x-pixel maximum value on the screen.
  1022.           ymin determines the window y-pixel minimum value on the screen.
  1023.           ymax determines the window y-pixel maximum value on the screen.
  1024.           
  1025.           EXAMPLES: 
  1026.           
  1027.           ustart("high2",0.0,640,0.0,400.0); 
  1028.           
  1029.           will create an Amiga window that fills the screen.  
  1030.           
  1031.           
  1032.           ustart("high1",0.0,320.0,0.0,100.0); 
  1033.           
  1034.           will  create an Amiga window that fills the lower left quarter of
  1035.           the screen.  
  1036.           
  1037.           
  1038.           ustart("high2.backdrop",0.0,640.0,0.0,400.0); 
  1039.           
  1040.           will create a Amiga window that fills  the  entire  screen.    No
  1041.           borders will be shown.  You can draw on the entire screen.  
  1042.           
  1043.           
  1044.           
  1045.      
  1046.      uend(); 
  1047.      
  1048.           Stops everything.      Call  this  when  you  are  through  doing
  1049.           graphics.  UEND closes  the  window,  the  screen,  the  graphics
  1050.           libraries, frees storage allocated by GWIN, etc.  Be sure to call 
  1051.           this routine before exiting your application program.  
  1052.           
  1053.  
  1054.  
  1055.                                       -16-
  1056.  
  1057.  
  1058.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1059.  
  1060.  
  1061.           
  1062.           
  1063.      
  1064.      udarea(xmin,xmax,ymin,ymax);
  1065.      float xmin,xmax,ymin,ymax;
  1066.      
  1067.           Default  active  region  boundaries if UWINDO is not called: Full
  1068.           active window region selected by USTART.  
  1069.           
  1070.           Determines the active region of the full  display  region.    The
  1071.           minimum and maximum values are expressed as percents of the x and 
  1072.           y full  screen  limits.    UDAREA may be called at any time after
  1073.           USTART and may be used to  define  the  active  sub-area  of  the
  1074.           screen.   All input values to this procedure must be in the range
  1075.           [0.0,100.0]. The xmin value must be less than the xmax value  and
  1076.           the ymin value must be less than the ymax value.  
  1077.           
  1078.           EXAMPLES: 
  1079.           
  1080.           udarea(0.0,100.0,0.0,100.0); 
  1081.           
  1082.           Allows use of the entire graphics region of the window.  
  1083.           
  1084.           udarea(10.,20.,10.,20.); 
  1085.           
  1086.           Allows  use  of  a  square sub-region of the full graphics region
  1087.           defined by USTART. All graphics operations are clipped and scaled 
  1088.           to this region unless you turned clipping off with uset("ncli").  
  1089.           
  1090.           
  1091.           
  1092.      
  1093.      uwindo(xmin,xmax,ymin,ymax);
  1094.      float xmin,xmax,ymin,ymax;
  1095.           
  1096.           Default  virtual  window  boundaries  if   UWINDO   not   called:
  1097.           [0.0,100.0] x and [0.0,100.0] y.  
  1098.           
  1099.           Determines the  virtual window boundaries.  Everything inside the
  1100.           bounds will be mapped and plotted into the current active  region
  1101.           of  the screen as determined by USTART or UDAREA. Any real values
  1102.           may be used for the values input to this procedure.  Xmin must be 
  1103.           less than xmax and ymin must be less than ymax.   Calls  to  this
  1104.           procedure  allow  pan  and  zoom  operations  (not like real-time
  1105.           smooth pan and zoom however.   You  must  clear  the  screen  and
  1106.           redraw everything to see the panned or zoomed image.) 
  1107.           
  1108.           EXAMPLES: 
  1109.           
  1110.           uwindo(0.,100.,0.,100.); 
  1111.           
  1112.           Sets  the  virtual  window  to  [0.0,100.0]  x and [0.0,100.0] y.
  1113.           Every part of your image that has coordinates falling  into  this
  1114.           square will be mapped and plotted to the active graphics region.  
  1115.           
  1116.           uwindo(-50.,150.,-50.,150.); 
  1117.           
  1118.           Backs  away  or  zooms  out  from  the  previous  window setting.
  1119.  
  1120.  
  1121.                                       -17-
  1122.  
  1123.  
  1124.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1125.  
  1126.  
  1127.           Everything that was drawn with the previous window setting  would
  1128.           be  drawn  twice  as  small in the center of the screen with this
  1129.           window setting.  
  1130.           
  1131.           
  1132.           
  1133.      
  1134.      umove(x,y);
  1135.      float x,y;
  1136.      
  1137.           Moves the beam (invisibly) to the  specified  virtual  coordinate
  1138.           point  (with  respect  to the virtual window set up in UWINDO.) X
  1139.           and y may assume any legal floating point values.  
  1140.           
  1141.           
  1142.           
  1143.      
  1144.      udraw(x,y);
  1145.      float x,y;
  1146.      
  1147.           Draws a line using  the  current  color  from  the  current  beam
  1148.           position  to  the new beam position designated in the UDRAW call.
  1149.           Updates the current beam position to the new position.  X  and  y
  1150.           are  floating  point  numbers and are with respect to the virtual
  1151.           window set up in UWINDO.  They  may  assume  any  legal  floating
  1152.           point values.    The  resulting line will be clipped as necessary
  1153.           unless you turned clipping off with uset("ncli").  
  1154.           
  1155.           
  1156.           
  1157.      
  1158.      uwhere(&x,&y);
  1159.      float x,y;
  1160.      
  1161.           Returns the virtual coordinates of  the  current  beam  position.
  1162.           Note that this procedure uses ADDRESSES of the variables.  
  1163.           
  1164.           
  1165.           
  1166.      
  1167.      urect(x1,y1,x2,y2);
  1168.      float x1,y1,x2,y2;
  1169.      
  1170.           Draws  a  rectangle  outline  in the current color whose opposite
  1171.           corner points are (x1,y1) and (x2,y2). Fills the  rectangle  with
  1172.           the current  color  if the USET "fill" option is in effect.  This
  1173.           routine is much faster than calling  a  four-sided  polygon  with
  1174.           uplygn.  
  1175.           
  1176.           
  1177.           
  1178.      
  1179.      uplygn(x,y,n,r);
  1180.      float x,y,n,r;
  1181.      
  1182.           Draws a regular n-sided polygon whose circumscribing circle is of 
  1183.           radius "r" and whose center is at (x,y). Fills the polygon if the 
  1184.           USET "fill"  option  is in effect.  Current color (previously set
  1185.  
  1186.  
  1187.                                       -18-
  1188.  
  1189.  
  1190.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1191.  
  1192.  
  1193.           by the UPSET "colo" option) is applied.  
  1194.           
  1195.           
  1196.           
  1197.      
  1198.      ucrcle(x,y,r);
  1199.      float x,y,r;
  1200.      
  1201.           Draws a circle of radius "r" centered at (x,y).  Uses  the  Amiga
  1202.           Ellipse  or  AreaEllipse  routine  unless  the circle exceeds the
  1203.           bounds of the viewing area.  When  this  occurs,  the  circle  is
  1204.           merely a  clipped  30  sided  polygon.    If  you  need  a higher
  1205.           resolution circle in this case, call uplygn with more sides.  
  1206.           
  1207.           
  1208.           
  1209.      
  1210.      uoutln(); 
  1211.      
  1212.           Draws a border around the current active graphics region  in  the
  1213.           current color.    If  the USET "fill" option is on, the region is
  1214.           filled with the current color.  
  1215.           
  1216.           
  1217.           
  1218.      
  1219.      uerase(); 
  1220.      
  1221.           Erases the current active graphics region as defined  by  UDAREA.
  1222.           The  region  is  filled with the "ccol" or "clear color" that was
  1223.           set with UPSET. (The default is black.) 
  1224.           
  1225.           
  1226.           
  1227.      
  1228.      uadjust(x,y,&xadj,&yadj);
  1229.      float x,y,xadj,yadj;
  1230.      
  1231.           This converts the coordinate (x,y) to  display  coordinates  then
  1232.           converts  the  display  coordinates  back  to our current virtual
  1233.           coordinates and provides them to you as  (xadj,yadj).  Since  the
  1234.           display  coordinates are discrete and the virtual coordinates are
  1235.           not, there are times when you need to know what  the  mapping  is
  1236.           doing with  your  coordinates.    This  allows  you  to  "adjust"
  1237.           coordinates to the discrete coordinate space.  An  example  would
  1238.           be if you wanted two lines side by side and didn't want to try to 
  1239.           calculate  the  mapping  from  your  virtual  coordinates  to the
  1240.           display's discrete coordinates.  UADJUST can be  used  to  figure
  1241.           out  the  mapping  since it "adjusts" your virtual coordinates to
  1242.           the virtual equivalent of the nearest discrete point  in  display
  1243.           space.  
  1244.           
  1245.           
  1246.           
  1247.      
  1248.      urotate(x,y,theta);
  1249.      float x,y,theta;
  1250.      
  1251.  
  1252.  
  1253.                                       -19-
  1254.  
  1255.  
  1256.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1257.  
  1258.  
  1259.           Rotates  the  virtual  coordinate  system  through an angle theta
  1260.           (value 0.0 through 360.0) relative to  the  point  (x,y)  in  the
  1261.           virtual coordinate  space.    (x,y) is ALWAYS with respect to the
  1262.           ORIGINAL UNROTATED COORDINATE  SYSTEM.  The  origin  of  the  new
  1263.           coordinate  system  (0,0)  is  located  at  (x,y) of the original
  1264.           unrotated coordinate system.  There is no way provided to  rotate
  1265.           Amiga text.   The position at which the text is to appear will be
  1266.           rotated and the text will begin at the new position but  it  will
  1267.           still be horizontal like this line you are reading.  
  1268.           
  1269.           
  1270.           
  1271.      
  1272.      ugrin(&x,&y);
  1273.      float x, y;
  1274.      
  1275.           Graphic  input  routine for responding to MOUSEBUTTONS. When this
  1276.           procedure is called, your application waits for the user to press 
  1277.           the left mouse button.  When  he  does,  UGRIN  returns  to  your
  1278.           program with the virtual coordinates of the point selected by the 
  1279.           user.  Use this for selecting things with the mouse button.  Also 
  1280.           use  this if you want the display to pause long enough for you to
  1281.           see what you have drawn!  
  1282.           
  1283.           
  1284.           
  1285.      
  1286.      ugrinc(&x,&y,&event,&key);
  1287.      float x, y;
  1288.      long event;
  1289.      char key;
  1290.      
  1291.           Graphic  input  routine  for  responding  to   MOUSEBUTTONS   and
  1292.           VANILLAKEY.   UGRINC  returns the x and y location of the cursor,
  1293.           the event type, and the keyboard character (KEY) that was pressed 
  1294.           if the event  type  was  "VANILLAKEY".  If  the  event  type  was
  1295.           "MOUSEBUTTONS",  the KEY returned is an "a" if it was a mouse key
  1296.           "down" event code and an "A" if it was a  mouse  key  "up"  event
  1297.           code.  MOUSEMOVE events are NOT monitored by UGRINC.  
  1298.           
  1299.           Note  that  the  definition  of  the  variables  MOUSEBUTTONS and
  1300.           VANILLAKEY    reside    in     the     Amiga     include     file
  1301.           "intuition/intuition.h"  and  this file should be included if you
  1302.           wish to check the EVENT for these types.  (For  what  its  worth,
  1303.           MOUSEBUTTONS   is  defined  as  "8",  VANILLAKEY  is  defined  as
  1304.           "0x00200000L".) 
  1305.           
  1306.           UGRINC also informs you of the "WINDOWCLOSE" event  if  the  USET
  1307.           option "nclo"  is  in  effect.    (If  its opposite, "clos", (the
  1308.           default)  is  in  effect,  the  program  closes  everything  down
  1309.           automatically and exits.) 
  1310.           
  1311.           UGRINC also  informs  you of "REFRESHWINDOW" events.  If the user
  1312.           resizes the window, the display is destroyed.  You should  redraw
  1313.           the entire display upon receiving this event.  
  1314.           
  1315.           
  1316.           
  1317.  
  1318.  
  1319.                                       -20-
  1320.  
  1321.  
  1322.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1323.  
  1324.  
  1325.      
  1326.      ugrinl(&x,&y,&event,&key);
  1327.      float x, y;
  1328.      long event;
  1329.      char key;
  1330.      
  1331.           Same  as  UGRINC  above  except  UGRINL  also  reports  MOUSEMOVE
  1332.           (locator) events.   If  the  user  moves  the  mouse,  the  (x,y)
  1333.           coordinate  of  the  current  mouse  position in virtual space is
  1334.           provided to you.  This is useful for  making  running  coordinate
  1335.           displays on  the  screen.    (I  have  been  doing  speech signal
  1336.           processing and find it useful for  displaying  microseconds  from
  1337.           the  beginning of a segment of speech as I move the cursor within
  1338.           the waveform.  The microsecond display updates in real-time as  I
  1339.           move the cursor.) Now not EVERY MOUSEMOVE event is provided - you 
  1340.           wouldn't  have  time  to  respond  to them all - but the last one
  1341.           reported in a series is reported to you.  It provides all of  the
  1342.           ones that you could hope to use.  
  1343.           
  1344.           
  1345.           
  1346.      
  1347.      ugrina(&x,&y,&event,&key);
  1348.      float x, y;
  1349.      long event;
  1350.      char key;
  1351.      
  1352.           Same  as  ugrinl  except that ugrina does not enter a wait state.
  1353.           Ugrinc returns immediately with whatever events were generated by 
  1354.           the user if any.  Ugrina can be used within processing  loops  to
  1355.           give the user the option to abort a 5 hour Mandelbrot drawing for 
  1356.           example.  
  1357.           
  1358.           
  1359.           
  1360.      
  1361.      uigrina(&ix,&iy,&event,&key);
  1362.      int ix, iy;
  1363.      long event;
  1364.      char key;
  1365.      
  1366.           Same  as  ugrina  except  that uigrina does not make a coordinate
  1367.           transformation of the  returned  ix,  and  iy  cursor  coordinate
  1368.           data.   They  are  returned  as  integers  that  are  the  cursor
  1369.           coordinate  position  data  normally  reported  by  Amiga.   This
  1370.           increases the  speed  with which cursor tracking can occur.  This
  1371.           is useful if you are calling Amiga  graphics  functions  directly
  1372.           for speed.  
  1373.           
  1374.           
  1375.           
  1376.      
  1377.      ufont(name,size);
  1378.      char name[255];
  1379.      float size;
  1380.      
  1381.           Sets  the  current font and font size that will be used by UPRINT
  1382.           and UPRNT1.  FONTNAME may be the name of a font in the  directory
  1383.  
  1384.  
  1385.                                       -21-
  1386.  
  1387.  
  1388.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1389.  
  1390.  
  1391.           "sys:fonts"  that you wish to use or it may be the full path name
  1392.           of a font on any disk you have mounted.  An example of the former 
  1393.           would be ufont("topaz",11.0).  An example of the latter would  be
  1394.           ufont(  "df1:SlavicFonts/cyrillic/moskva.font", 11.0 ); from Fish
  1395.           disk 202.  You can use any font that is  in  Amiga  form.    Many
  1396.           fonts are available on the Fish disks for example.  
  1397.           
  1398.           GWIN searches  the  sys:fonts  directory first.  If the requested
  1399.           font is not  found,  GWIN  then  searches  the  disks.    If  the
  1400.           requested  font  is  still  not found, GWIN blinks the screen and
  1401.           writes an error message to the window in which you  started  your
  1402.           application.  
  1403.           
  1404.           Fonts provided by Amiga are in "sys:fonts".  Available font sizes 
  1405.           can  be obtained by listing the directory of the same name as the
  1406.           font.  For example allowable sizes for the "ruby" font are  12.0,
  1407.           15.0,  and  8.0  as  can  be  seen  when  you  list the directory
  1408.           sys:fonts/ruby.  The numbers that are printed are  the  allowable
  1409.           font sizes.  
  1410.           
  1411.           For example, the ones on my system are: 
  1412.           
  1413.           FONT                           AVAILABLE SIZES
  1414.           
  1415.           sys:fonts/curtools             16.0
  1416.           sys:fonts/frettools            10.0
  1417.           sys:fonts/ruby                 12.0, 15.0, 8.0
  1418.           sys:fonts/timetools            15.0
  1419.           sys:fonts/diamond              12.0, 20.0
  1420.           sys:fonts/garnet               16.0, 9.0
  1421.           sys:fonts/sapphire             14.0, 19.0
  1422.           sys:fonts/topaz                11.0
  1423.           sys:fonts/emerald              17.0, 20.0
  1424.           sys:fonts/opal                 12.0, 9.0
  1425.           sys:fonts/tab                  8.0
  1426.           
  1427.           
  1428.           
  1429.      
  1430.      uprint(x,y,data);
  1431.      float x,y;
  1432.      char data[255];
  1433.      
  1434.           Prints  the  data  in  "data"  beginning  at the virtual location
  1435.           (x,y).  "data" may be a character string or a real number.    The
  1436.           USET options "text", "real", and "inte" determine how "data" will 
  1437.           be interpreted.  If "text" is in effect, "data" is expected to be 
  1438.           a character string.  If "real" or "inte" are in effect, "data" is 
  1439.           expected to  be  a real number.  It will be converted to a string
  1440.           and printed as either a real number or an integer  in  accordance
  1441.           with whether "real" or "inte" is in effect.  
  1442.           
  1443.           
  1444.           
  1445.      
  1446.      uprnt1(option,data);
  1447.      char option[4],data[255];
  1448.      
  1449.  
  1450.  
  1451.                                       -22-
  1452.  
  1453.  
  1454.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1455.  
  1456.  
  1457.           Same  as  UPRINT except it prints at the current beam position as
  1458.           set by UMOVE or some other drawing operation.  OPTION is  "text",
  1459.           "real",  or  "inte".  The  provided  option  is in effect for the
  1460.           duration of the UPRNT1 call only.  Data must  be  either  a  text
  1461.           string or  a  real number.  (The "inte" option truncates the real
  1462.           number and prints an integer.) The beam position  is  updated  to
  1463.           the position  of  the  end of the string that was printed.  It is
  1464.           positioned properly for the beginning of the next string that you 
  1465.           may wish to print with UPRNT1. You can use  UWHERE  to  find  the
  1466.           virtual  location  of  this  point if you need to know where that
  1467.           point is.  
  1468.           
  1469.           
  1470.           
  1471.      
  1472.      uprscr(); 
  1473.      
  1474.           Dumps the screen image to the printer.  Works for an Epson LQ-850 
  1475.           and presumably will work for other similar printers.   Output  is
  1476.           sent to "par:", the parallel port.  
  1477.           
  1478.           
  1479.           
  1480.      
  1481.      uzvtodconv(x,y,&xt,&yt,&ix,&iy);
  1482.      float x,y;
  1483.      float xt,yt;
  1484.      long ix,iy;
  1485.      
  1486.           Converts  virtual coordinates (x,y) to screen display coordinates
  1487.           yielding floating point (xt,yt) and fixed point (ix,iy) values.  
  1488.           
  1489.           
  1490.           
  1491.      
  1492.      uzdtovconv(ix,iy,&x,&y);
  1493.      long ix,iy;
  1494.      float x,y;
  1495.      
  1496.           Converts  screen   display   coordinates   (ix,iy)   to   virtual
  1497.           coordinates (x,y).  
  1498.           
  1499.           
  1500.           
  1501.      
  1502.      uyorn(bodytext,positivetext,negativetext,width,height);
  1503.      char bodytext[],positivetext[],negativetext[];
  1504.      float width,height;
  1505.      
  1506.           Puts up  yes/no requester.  Returns true/false value depending on
  1507.           the choice made by the user.  Bodytext is the text of the yes  or
  1508.           no question  you  wish to ask the user.  Positivetext is the text
  1509.           that  will  be  displayed  with  the  positive   selection   box.
  1510.           Negativetext is the text that will be displayed with the negative 
  1511.           selection box.    Width  and  height  are the width and height in
  1512.           "percentage coordinates", i.e., a width and height  of  100  will
  1513.           fill the  whole screen.  A width and height of 50.0 will fill the
  1514.           upper left quarter of the screen.  The requester is always  drawn
  1515.  
  1516.  
  1517.                                       -23-
  1518.  
  1519.  
  1520.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1521.  
  1522.  
  1523.           beginning at the upper lefthand corner of the screen so width and 
  1524.           height are measured from that point.  
  1525.           
  1526.           
  1527.           
  1528.      
  1529.      uimove(ix,iy);
  1530.      long ix,iy;
  1531.      
  1532.           If  you  wish to bypass floating point and know exactly where you
  1533.           want your pixels to begin, use this command.  (Or you  could  use
  1534.           the  Amiga "Move" command because GWIN merely calls Move with the
  1535.           coordinates you pass in.) 
  1536.           
  1537.           
  1538.           
  1539.      
  1540.      uidraw(ix,iy);
  1541.      long ix,iy;
  1542.      
  1543.           If you know exactly where you want your pixels to fall, use  this
  1544.           command.  If  you  get  it wrong though anything can happen.  The
  1545.           Amiga does not respond well to data drawn outside of  the  bounds
  1546.           of the  screen.    It  is  possible to overwrite important things
  1547.           accidentally and cause GURUs.  This  command  merely  passes  the
  1548.           integer data (ix,iy) to the Amiga "Draw" command.  
  1549.           
  1550.           
  1551.           
  1552.      
  1553.      uamenu(gwinmenu0,gwinmenu1,gwinmenu2,text,comchr,mutex,flags,routine);
  1554.      long gwinmenu0,gwinmenu1,gwinmenu2,mutex;
  1555.      USHORT flags;
  1556.      char comchr;
  1557.      char text[255];
  1558.      long routine();
  1559.      
  1560.           Uamenu makes  creating  menus  easy.   The first three parameters
  1561.           define the menu that you are setting up.  Amiga menus have  three
  1562.           levels.   The  top  level (I'm calling it level 0) appears in the
  1563.           title bar when the right mouse button  is  depressed.    The  top
  1564.           level merely  gives the NAME of the menu.  It is highlighted when
  1565.           the mouse is placed over it.  A level 0 menu  cannot  select  any
  1566.           activity.   It  is  there  to  allow you to select a level 1 menu
  1567.           item.  A level 1 menu item can either cause an action to occur or 
  1568.           cause a level 2 menu to appear depending upon whether a  level  2
  1569.           menu is   attached.     Lets  consider  the  triplet  (gwinmenu0,
  1570.           gwinmenu1, gwinmenu2).  If the  values  are  (1,  0,  0)  we  are
  1571.           referring to  the first level 0 menu in the title bar.  (2, 0, 0)
  1572.           refers to the second level 0 menu in the title bar,  and  so  on.
  1573.           If the values are (3, 1, 0) we are referring to the first level 1 
  1574.           item in  the  third level 0 menu.  If the values are (3, 2, 4) we
  1575.           are referring to the fourth level 2 item in the  second  level  1
  1576.           menu in  the  third  level  zero  menu.   (Please see the example
  1577.           program "testmenu.c".) 
  1578.           
  1579.           Menus items can be referred to in any order.  GWIN will  fill  in
  1580.           with "dummy"  names and actions if necessary.  GWIN allocates all
  1581.  
  1582.  
  1583.                                       -24-
  1584.  
  1585.  
  1586.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1587.  
  1588.  
  1589.           storage necessary for the menus - and cleans up when you exit.  
  1590.           
  1591.           Text is the text that will appear in the menu bar.  
  1592.           
  1593.           Comchr is an Amiga "command character."  This is a character that 
  1594.           allows the menu item to be selected by depressing  the  character
  1595.           while holding  down  the  right  "Amiga" key.  Saves the user the
  1596.           trouble of having to actually use the menus if he  remembers  the
  1597.           "command character."    If  "comchr" is chosen to be ' ', i.e., a
  1598.           blank, there will be no "command character" associated  with  the
  1599.           designated menu  item.   A command character appears to the right
  1600.           of the text within the menu item preceded by a symbol  indicating
  1601.           the right Amiga key.  
  1602.           
  1603.           Mutex contains  mutual  exclusion bits.  These bits may be set to
  1604.           indicate which other menu items on  this  same  level  should  be
  1605.           deselected when  this  menu item is selected.  If mutex is set to
  1606.           0, no mutual exclusion occurs.  For most normal menus you  should
  1607.           set  mutex  to 0. Setting bit 0 to 1 means that the first item in
  1608.           the menu list is excluded by selecting this item.  Setting bit  5
  1609.           to  1  means  that the fifth item in the menu list is excluded by
  1610.           selecting this item, etc.  
  1611.           
  1612.           Flags contains flag bits that  provide  additional  control  over
  1613.           menus and  menu  items.  If you are addressing a level zero menu,
  1614.           only two flag bits are active: 
  1615.           
  1616.                MENUENABLED - When set means that  the  menu  is  ready  for
  1617.                action.  When not set the menu and its items are disabled.  
  1618.                
  1619.                MIDRAWN - When set means that the menu is display.  The menu 
  1620.           is not displayed when MIDRAWN is not set.  
  1621.           
  1622.           If  you  are  addressing  a  level  one  or  level  two menu, the
  1623.           following flags have meaning: 
  1624.           
  1625.           CHECKIT - Places a check mark in front of  an  item  when  it  is
  1626.                selected.   If  you use this flag, you should leave room for
  1627.                the check mark by having 3 or 4 leading blanks in the "text" 
  1628.                parameter.  
  1629.                
  1630.           CHECKED - Places a check mark in front of an item when  the  menu
  1631.                first comes up.  
  1632.                
  1633.           ITEMTEXT  -  Indicates  that  the  menu  item is text rather than
  1634.                graphics.  The current version of  GWIN  allows  text  only.
  1635.                You must set this flag.  
  1636.                
  1637.           COMMSEQ -  Indicates  that  there  is a command key sequence.  If
  1638.                comchr is set non-blank, you should set COMMSEQ if you  wish
  1639.                the command key to appear in the menu bar.  
  1640.                
  1641.           ITEMENABLED -  Enables  menu  item.   You must set ITEMENABLED in
  1642.                this version of GWIN.  
  1643.                
  1644.                One of the following three menu highlighting flags must be set: 
  1645.                
  1646.           HIGHCOMP - Complements all bits of this menu item's menu bar when 
  1647.  
  1648.  
  1649.                                       -25-
  1650.  
  1651.  
  1652.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1653.  
  1654.  
  1655.                it is selected.  Gives a visual indication to the user.  
  1656.                
  1657.           HIGHBOX - Draws a box outside this item's select box.  
  1658.                
  1659.           HIGHNONE - Specifies no highlighting.  
  1660.                
  1661.           
  1662.           Routine is a function pointer that points to  the  function  that
  1663.           you  wish control transferred to when this menu item is selected.
  1664.           This is a function in your program that you design to  carry  out
  1665.           the activity selected by the user.  
  1666.           
  1667.           
  1668.           UAMENU EXAMPLES: 
  1669.           
  1670.           The following are examples of valid uamenu calls: 
  1671.           
  1672.         uamenu(1,0,0,"test1",' ',0,MIDRAWN|MENUENABLED,0); 
  1673.           
  1674.         uamenu(1,1,0,"test2",' ',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1675.                   |ITEMENABLED,function110); 
  1676.           
  1677.         uamenu(1,1,1,"test3",'B',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1678.                   |COMMSEQ|ITEMENABLED,function111); 
  1679.           
  1680.         uamenu(1,2,0," test4",'C',0,MIDRAWN|ITEMTEXT|HIGHCOMP 
  1681.                   COMMSEQ|CHECKIT|ITEMENABLED,function120); 
  1682.           
  1683.           
  1684.           
  1685.      
  1686.      usetrgb(colorindex,redvalue,greenvalue,bluevalue);
  1687.      float colorindex,redvalue,greenvalue,bluevalue;
  1688.      
  1689.           Sets  the  color  register indirectly pointed to by colorindex to
  1690.           have the designated red, green and blue values.  See appendix  to
  1691.           see   which   Amiga   color  registers  are  pointed  to  by  the
  1692.           colorindex.  The red green  and  blue  values  are  converted  to
  1693.           integers and each must be in the range 0 to 15.  
  1694.           
  1695.           
  1696.           
  1697.      
  1698.      ugetrgb(colorindex,&redvalue,&greenvalue,&bluevalue);
  1699.      float colorindex;
  1700.      float redvalue,greenvalue,bluevalue;
  1701.      
  1702.           Retrieves  the  red,  green and blue values of the color register
  1703.           indirectly pointed to by colorindex.  
  1704.           
  1705.           
  1706.           
  1707.      
  1708.      ugetstring(x,y,width,prompt,text);
  1709.      float x,y,width;
  1710.      char prompt[],text[];
  1711.      
  1712.           Puts a requester on the screen and waits for the user to type  in
  1713.  
  1714.  
  1715.                                       -26-
  1716.  
  1717.  
  1718.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1719.  
  1720.  
  1721.           a string.    X and y gives the coordinates of the upper left hand
  1722.           corner of the requester  box.    These  coordinates  are  virtual
  1723.           coordinates.   Width  gives  the  width of the requester box as a
  1724.           virtual x coordinate distance.  Prompt is a text string that  you
  1725.           provide  that  lets  the user know what sort of data (string) you
  1726.           are expecting from him.    "Text"  should  be  declared  in  your
  1727.           calling program  as  a length 255 character array.  Prompt may be
  1728.           up to 255 characters.  (They probably won't all fit on the screen 
  1729.           if you use them all.) The font assumed within  the  requester  is
  1730.           "topaz.font",  size 8. (It comes with the machine, I expect it to
  1731.           be available...) 
  1732.           
  1733.           
  1734.           
  1735.      
  1736.      usetcleanup(cleanup_routine);
  1737.      long cleanup_routine();
  1738.      
  1739.           This allows you to have your own cleanup routine.  It is possible 
  1740.           for the user to exit a GWIN-based application by clicking on  the
  1741.           close window  gadget.    (Unless  the  "nclo"  uset  option is in
  1742.           effect.) If you had done memory allocation in your application or 
  1743.           left the sound on, etc, having your own  cleanup  routine  allows
  1744.           you to  clean  those  things up.  When the close window gadget is
  1745.           selected, GWIN cleans up all of its  storage  allocation,  window
  1746.           and screen allocations, closes libraries it opened, etc.  Control 
  1747.           is then passed to your cleanup routine if you specified one via a 
  1748.           usetcleanup call.   Cleanup_routine is a function pointer to your
  1749.           cleanup routine.  For an example, see routines  in  the  examples
  1750.           directory.  
  1751.           
  1752.           
  1753.           
  1754.      
  1755.      uset(option);
  1756.      char option[4];
  1757.      
  1758.           
  1759.           OPTION: 
  1760.           
  1761.           "fill"    Turns on polygon fill mode.
  1762.           
  1763.           "nofi"    Turns off polygon fill mode.  Closes and fills
  1764.                current polygon. (DEFAULT)
  1765.           
  1766.           "text"    Sets text mode for UPRINT.  UPRINT assumes input
  1767.                was a character string.  (DEFAULT)
  1768.           
  1769.           "inte"    Sets "integer" mode for UPRINT.  UPRINT assumes
  1770.                input was a floating point number that should be
  1771.                truncated and displayed as an integer.
  1772.           
  1773.           "real"    Sets "real" mode for UPRINT.  UPRINT assumes input
  1774.                was a floating point number that should be displayed
  1775.                as a floating point number.
  1776.           
  1777.           "clip"    Turns polygon and line clipping on.   (DEFAULT)
  1778.           
  1779.  
  1780.  
  1781.                                       -27-
  1782.  
  1783.  
  1784.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1785.  
  1786.  
  1787.           "ncli"    Turns polygon and line clipping off.  Use this
  1788.                only when you are absolutely certain that your
  1789.                drawing will be confined to the active graphics
  1790.                region!
  1791.           
  1792.           "rint"    If polygon "fill" mode is on and "rint" is on,
  1793.                then only the interior of rectangles plotted
  1794.                using URECT will be filled.  Their borders will
  1795.                be unchanged.
  1796.           
  1797.           "rext"    If polygon "fill" mode is on and "rext" is on,
  1798.                then the whole polygon including the border will
  1799.                be filled with the current color when URECT is called.
  1800.           
  1801.           "clos"    Allows UGRIN, UGRINL, and UGRINC to close down
  1802.                the GWIN graphics system and exit back to the
  1803.                system if the user selects the close window
  1804.                gadget.  (DEFAULT)
  1805.           
  1806.           "nclo"    Allows UGRINL, UGRINC and UGRINA to report the
  1807.                CLOSEWINDOW event to your program.  No shutdown
  1808.                of the GWIN system results.  It is then up to
  1809.                you to issue the UEND() call.  This option allows
  1810.                you to handle the problem of freeing storage
  1811.                areas you may have allocated in your main
  1812.                program among other things.  NOTE:  UGRIN
  1813.                exits any time the CLOSEWINDOW gadget is
  1814.                selected by the user.  The "nclo" option has
  1815.                no effect on UGRIN.
  1816.           
  1817.           "comp"    Color "complement" mode.  The color with which to
  1818.                draw is selected by calling upset("colo",xx).  The
  1819.                number xx is mapped to an Amiga "color register".
  1820.                Let's say that xx maps to color register rr.
  1821.                (See appendix for GWIN color mapping information.)
  1822.                Each color register contains red/green/blue values
  1823.                that determine the color drawn when that color register
  1824.                is used.  When "comp" is in effect, instead of using
  1825.                color register rr for drawing, each pixel in the
  1826.                display bitmap that would have been drawn using rr is
  1827.                examined to see what color register generated it and
  1828.                then the complement of that register number is
  1829.                substituted for that pixel.  Each pixel that would
  1830.                have been drawn using rr changes color.  If you draw
  1831.                a line or an object once using complement mode, the
  1832.                line or object appears.  If you draw it again, it
  1833.                disappears and the screen image returns to its exact
  1834.                original state.  Complement mode is used for drawing
  1835.                rubberband lines, rubberband boxes, and placing objects.
  1836.                I have arranged the color map so that if the background
  1837.                color of the region over which you are drawing in
  1838.                complement mode is black (the default), then the
  1839.                colors drawn in complement mode will be what you expect,
  1840.                i.e., red will be red, blue will be blue, etc.
  1841.                This requires black to be assigned to color register
  1842.                zero and the current drawing color to be placed in register
  1843.                15 or 31 depending upon the number of colors allowed for
  1844.                the type of screen you have chosen.  This is why certain
  1845.  
  1846.  
  1847.                                       -28-
  1848.  
  1849.  
  1850.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1851.  
  1852.  
  1853.                colors (such as red) are repeated in the colormap.
  1854.           
  1855.           "ncom"    Turns complement mode off.
  1856.           
  1857.           
  1858.           
  1859.      
  1860.      upset(option,value);
  1861.      char option[4];
  1862.      float value;
  1863.      
  1864.      
  1865.           
  1866.           OPTION    VALUE                   ACTION
  1867.           
  1868.           "colo"    0.0 through 31.0        Set current color for drawing.  See
  1869.                                        Appendix 1 for color map.  (Sets
  1870.                                        "A" pen and "O" pen.)
  1871.           
  1872.           "acol"    0.0 through 31.0        Set current color for A pen only.
  1873.           
  1874.           "ocol"    0.0 through 31.0        Set current color for O pen only.
  1875.           
  1876.           "bcol"    0.0 through 31.0        Set current color for background
  1877.                                        color.  Background refers to text
  1878.                                        background.
  1879.           
  1880.           "ccol"    0.0 through 31          Set current color for clearing
  1881.                                        active graphics region when UERASE
  1882.                                        is called.
  1883.           
  1884.           "fsty"    0.0 through 16.0        Set font style.  Amiga allows
  1885.                                        the following font style settings
  1886.                                        to be applied to font sets that
  1887.                                        allow such settings:
  1888.           
  1889.                                        0.0 = DEFAULT
  1890.                                        1.0 = Underlined
  1891.                                        2.0 = bold
  1892.                                        4.0 = italic
  1893.                                        8.0 = wider
  1894.           
  1895.                                        Add the values of each of the above
  1896.                                        that you wish to choose and use
  1897.                                        the result as "VALUE" when you
  1898.                                        call UPSET with the "fsty" option.
  1899.           
  1900.           
  1901.           
  1902.           
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.                                       -29-
  1914.  
  1915.  
  1916.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1917.  
  1918.  
  1919.                                    APPENDIX 1
  1920.      
  1921.      
  1922.             GLOBAL VARIABLES AND CONSTANTS IN GWIN MODULE ACCESSIBLE
  1923.                       FROM PROGRAMS WHICH LINK WITH GWIN:
  1924.      
  1925.      #define SCR_MAX 2
  1926.      #define WIN_MAX 50
  1927.      #define MAXVECTORS 1000
  1928.      
  1929.      struct RastPort *rport1;
  1930.      struct Window *win[WIN_MAX];
  1931.      struct Screen *scr[SCR_MAX];
  1932.      
  1933.      struct GfxBase *GfxBase;
  1934.      struct IntuitionBase *IntuitionBase;
  1935.      struct DiskfontBase *DiskfontBase;
  1936.      
  1937.      Rport1  is  the  raster  port pointer that you would use if you issued
  1938.      your own Amiga graphics routine call.  It is  possible  while  in  the
  1939.      GWIN system  to call Amiga graphics routines.  You must then of course
  1940.      insure that your graphics figures do not exceed the established  pixel
  1941.      boundaries.   You  should not find it necessary to make such calls and
  1942.      they are discouraged generally - but if you need to, want to, and  are
  1943.      willing to assume the GURU risks, feel free.  
  1944.      
  1945.      Win[0] is  the  pointer  to  the window that GWIN is using.  (Multiple
  1946.      windows are not allowed within  GWIN  at  present.    You  could  open
  1947.      another  window  of  your  own  for  your  own  purposes  using Scr[0]
  1948.      presumably - at your risk.) It is available for use if  you  need  it.
  1949.      Hopefully you  won't.    Don't  close the window yourself in any case.
  1950.      GWIN closes everything and releases all allocated space when you  call
  1951.      UEND().  
  1952.      
  1953.      Scr[0] is  the  pointer  to  the screen that GWIN is using.  (Multiple
  1954.      screens are not allowed at present.) It is available for  use  if  you
  1955.      need it.  Hopefully you won't.  Don't close the screen yourself in any 
  1956.      case.   GWIN  closes  everything  it  opened and releases all space it
  1957.      allocated when you call UEND().  
  1958.      
  1959.      The MAX_VECTOR variable refers to the maximum number of sides that can 
  1960.      be handled by uplygn.  You will NOT need a 1000  sided  polygon.    It
  1961.      will  merely  look  like  a  VERY  slowly drawn circle and a 100 sided
  1962.      polygon is a nearly perfect approximation.  You  could  also  bump  up
  1963.      against  this limit if you do too many UDRAWS in a row without doing a
  1964.      UMOVE while in fill mode.  
  1965.      
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.                                       -30-
  1980.  
  1981.  
  1982.      17 Feb 1990                      GWIN            by Howard C. Anderson
  1983.  
  1984.  
  1985.                             COLOR TRANSLATION TABLE.
  1986.      
  1987.      Use these values for color_value in upset("colo",color_value) calls to 
  1988.      obtain the corresponding color.  
  1989.      
  1990.      black = 0.0;
  1991.      red = 1.0;
  1992.      green = 2.0;
  1993.      blue = 3.0;
  1994.      cyan = 4.0;
  1995.      yellow = 5.0;
  1996.      magenta = 6.0;
  1997.      white = 7.0;
  1998.      darkred = 8.0;
  1999.      darkgreen = 9.0;
  2000.      darkblue = 10.0;
  2001.      orange = 11.0;
  2002.      lime = 12.0;
  2003.      forestgreen = 13.0;
  2004.      aqua = 14.0;
  2005.      red2 = 15.0;
  2006.      violet = 16.0;
  2007.      brickred = 17.0;
  2008.      grey = 18.0;
  2009.      goldorange = 19.0;
  2010.      skyblue = 20.0;
  2011.      redorange = 21.0;
  2012.      brown = 22.0;
  2013.      pink = 23.0;
  2014.      purple = 24.0;
  2015.      tann = 25.0;
  2016.      bluegreen = 26.0;
  2017.      darkbrown = 27.0;
  2018.      lightaqua = 28.0;
  2019.      cadyellow = 29.0;
  2020.      white2 = 30.0;
  2021.      red3 = 31.0;
  2022.      
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.                                       -31-
  2046.  
  2047.  
  2048.      17 Feb 1990                      GWIN            by Howard C. Anderson
  2049.  
  2050.  
  2051.                    ACTUAL COLOR REGISTER ASSIGNMENTS IN GWIN
  2052.      
  2053.      Normally you    would't    use    these.         You     would     use
  2054.      upset("colo",(float)color_number)  where  color_number is given in the
  2055.      color translation table above.  The "actual color register" numbers in 
  2056.      this table  would  be  used  only  if  you  wished  to  directly  call
  2057.      SetAPen(rport1,number)   or   other   similar   Amiga  call  directly.
  2058.      (Allowable but discouraged.) 
  2059.      
  2060.       black = 0;
  2061.       blue = 1;
  2062.       red = 2;
  2063.       green = 3;
  2064.       cyan = 4;
  2065.       magenta = 5;
  2066.       lime= 6;
  2067.       yellow = 7;
  2068.       aqua = 8;
  2069.       darkblue = 9;
  2070.       darkgreen = 10;
  2071.       darkred = 11;
  2072.       forestgreen = 12;
  2073.       orange = 13;
  2074.       white = 14;
  2075.       red2 = 15;
  2076.      
  2077.       violet = 16;
  2078.       brickred = 17;
  2079.       grey = 18;
  2080.       goldorange = 19;
  2081.       skyblue = 20;
  2082.       redorange = 21;
  2083.       brown = 22;
  2084.       pink = 23;
  2085.       purple = 24;
  2086.       tann = 25;
  2087.       bluegreen = 26;
  2088.       darkbrown = 27;
  2089.       lightaqua = 28;
  2090.       cadyellow = 29;
  2091.       white2 = 30;
  2092.       red3 = 31;
  2093.      
  2094.      
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.                                       -32-
  2112.